4.1 Developing Software In a Team: Code Review（整理版）

原始笔记: 4.1 Code Review.md 原始教程: 4.1 Developing Software In a Team: Code Review created: 2026-07-29 10:55 整理说明: 本版本保持原笔记的协作模型、code review 技术和审查检查清单，只用教程补充这些知识点之间的关系；GitHub GUI 操作仍以原始教程为准。

内容简要概括

团队可以采用 Fork and Pull Model 或 Shared Repository Model 协作，但无论仓库权限如何安排，都应通过 feature branch 和 PR 隔离、审查变更。Code review 的重点是确认改动符合需求、可读、最小、结构清晰且文档同步；可以自动化检查的问题交给 CI，既有问题和架构重写则应拆成独立工作。

code review、Pull Request、Fork and Pull Model、Shared Repository Model、feature branch、base branch、compare branch、pair programming、CI、review checklist、最小改动、软件质量

1. Collaborative Code Development Models

团队如何向共享代码库贡献改动，取决于项目采用的协作模型。常见方式有 Fork and Pull Model 和 Shared Repository Model。

1.1 Fork and Pull Model

核心特点是：每个贡献者先拥有自己的仓库副本。

原始仓库
→ Fork 到个人账号
→ 在个人仓库的 feature branch 修改代码
→ Push 到个人仓库
→ 向原始仓库提交 Pull Request
→ 维护者审查并合并

贡献者不需要原始仓库的写权限，因此这种模型适合：

开源项目；
外部贡献者；
尚未加入核心团队的协作者；
需要让贡献者相对独立工作的场景。

1.2 Shared Repository Model

核心特点是：团队成员在同一个仓库中协作。

共享仓库
→ 创建 feature branch
→ 修改并 push
→ 从 feature branch 创建 PR
→ 团队审查
→ 合并到 develop 或 main

团队成员具有共享仓库的写权限，但仍应避免直接向主要分支提交未经审查的改动。通常用 feature branch 隔离工作，并保护 main：

main 只保留 production-ready 的版本；
develop 保留已经经过较充分测试、准备继续集成的代码；
feature branch 保存单项、自包含的改动。

这种模型需要更多权限与协作约定，适合稳定团队和组织内部项目。

1.3 两种模型的共同原则

两种模型的主要差异是 feature branch 位于个人 fork 还是共享仓库。它们都应遵循：

在独立分支完成变更；
通过 PR 说明改动目标；
在合并前进行 code review；
根据 review 反馈继续提交修正；
审查通过后再合并到 base branch。

2. Code Review 技术

Code review 是由代码作者以外的一个或多个人检查变更的质量保证过程。它不仅能较早发现问题，还能传播代码库知识，并迫使作者清楚表达设计依据。

常见技术包括：

Over-the-shoulder code review：一名开发者在同一台机器前向另一名开发者讲解改动；
Pair programming：两名开发者同时工作，一人编写代码，另一人实时反馈；
Formal code inspection：多人按照正式流程检查代码、规范或设计中的缺陷；
Tool-assisted code review：使用 GitHub 等工具异步检查代码并提交反馈。

不同团队可以尝试多种方式，再根据团队规模、时区、变更风险和沟通习惯选择合适流程。

3. 通过 Pull Request 进行审查

PR 用于通知团队：某个分支中的改动已经准备好接受讨论和审查。

作者编写并提交代码
→ 创建 Pull Request
→ Reviewer 检查并提交意见
→ 作者修改或回复
→ Reviewer 复查并解决意见
→ Approve
→ 合并并删除已完成的 feature branch

3.1 Base Branch 与 Compare Branch

base branch：改动准备合并进入的目标分支；
compare branch：包含待审查改动的 feature branch。

在 Fork and Pull Model 中，compare branch 通常位于个人 fork；在 Shared Repository Model 中，它通常位于共享仓库。

3.2 GitHub GUI 操作

原笔记明确将 GitHub 上创建、审查和处理 PR 的 GUI 操作留给教程。需要实际操作时，从原始教程的 Raising a Pull Request 开始阅读。

4. Code Review 检查清单

审查前先理解代码应该做什么：

阅读 specification 或 user requirements；
阅读 PR 描述；
必要时向作者确认需求；
明确此次变更的范围和验收条件。

理解目标后，再从以下方面检查改动。

4.1 改动是否可读

变量和函数名是否遵循命名规范；
if 条件的意图是否清晰；
函数名是否与实际行为一致；
阅读者是否能够在不过度追踪上下文的情况下理解代码。

4.2 是否是最小改动

是否重新实现了代码库或已有库中已经存在的功能；
是否加入了 requirement、Issue 或 ticket 未要求的功能；
是否混入与本次目标无关的格式化、重构或清理。

4.3 结构是否清晰

函数是否只做一件事；
模块化程度是否合适；
新代码是否与代码库现有结构一致；
展示层、业务逻辑和数据处理职责是否发生不必要的混合。

4.4 文档是否同步

功能变化后，对应文档是否更新；
新函数是否具有必要的 API 文档或 docstring；
文档是否与实际行为一致；
注释是否解释复杂设计背后的“为什么”，而不是重复代码正在做什么。

4.5 测试是否覆盖预期行为

Review 不应靠人工执行代码来穷举 bug，而应确认变更附带了合理测试。检查测试是否覆盖：

代码中的主要执行路径；
每个条件的 True 和 False 分支；
空序列、单元素和多元素循环；
边界条件；
Reviewer 无法确定行为的输入；
需求明确要求的输出与错误情况。

5. 不应混入本次 Review 的问题

Review 的目标是让项目安全地继续前进，不应把 PR 变成无限扩张的改造任务。

以下问题应交给更合适的流程：

Linting 问题：交给 linter 和 CI 自动检查；
逐个寻找所有 bug：要求测试覆盖关键情况，而不是只靠人工阅读；
变更前已经存在的问题：建立独立 Issue 或 PR；
架构重写：提前进行设计讨论，必要时另开任务。

审查时间越长，收益通常会逐步降低。应优先指出影响正确性、需求、可读性和维护性的具体问题，不要让“完美”阻碍合理进展。

6. 让代码更容易审查

提交审查前，作者可以主动降低 Reviewer 的认知负担：

保持改动规模较小；
每个 commit 只表达一个逻辑变化；
在 PR 中清楚说明变更内容、目的和验证方法；
请求审查前先自行 review；
把格式化、重构和行为变化分成不同 commit。

小而自包含的 PR 更容易理解、验证、反馈和回滚，也更容易让 review 聚焦真正需要人工判断的部分。

4.1 Developing Software In a Team: Code Review